home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C / Applications / Python 1.3.3 / Python 133 SRC / Tools / bgen / README < prev    next >
Text File  |  1995-12-21  |  6KB  |  164 lines
  1. BGEN -- An Experiment: Automatic Generation of Extension Modules
  2. ================================================================
  3.  
  4. This directory contains BGEN -- a package that helps in generating
  5. complete source code for Python extension module.  It currently also
  6. contains a set of examples that were generated with BGEN.  These
  7. examples are mostly interfaces to a number of important managers in
  8. the Macintosh toolbox.
  9.  
  10.  
  11. Overview of Subdirectories
  12. --------------------------
  13.  
  14. Main subdirectories:
  15.  
  16. bgen    the code generator package
  17.  
  18. Example subdirectories:
  19.  
  20. ae    AppleEvents
  21. ctl    Controls
  22. cm    Component manager
  23. dlg    Dialogs
  24. evt    Events
  25. menu    Menus
  26. list    Lists
  27. qd    QuickDraw
  28. qt    QuickTime
  29. res    Resources
  30. snd    Sound
  31. win    Windows
  32.  
  33.  
  34. Contents of Subdirectories
  35. --------------------------
  36.  
  37. The contents of each example subdirectory is similar (<Foobar> is
  38. for instance AppleEvents, while <foo> is ae):
  39.  
  40. <foo>scan.py    Scan the <Foobar>.h header, generating <foo>gen.py
  41. <foo>gen.py    Output of <foo>scan.py, input for <foo>support.py
  42. <foo>edit.py    Manually written complement of <foo>gen.py, sometimes
  43. <foo>support.py    Generate <Foo>module.c from <foo>gen.py and <foo>edit.py
  44. <Foo>module.c    The interface module, ready to be compiled
  45. <Foobar>.py    Symbolic constants extracted from <Foobar.h>
  46.  
  47.  
  48. Tests and Examples
  49. ------------------
  50.  
  51. Other files in these subdirectories are usually examples using the
  52. extension.  If there's a file t<foo>.py, it usually is a really
  53. boring test program.
  54.  
  55. Some test programs contain pathnames that should be edited before
  56. trying them.
  57.  
  58. Some of the less boring tests and examples:
  59.  
  60. At the top level:
  61.  
  62. test.py        Application mainloop, uses most Mac extensions
  63.  
  64. In ae:
  65.  
  66. aetools.py    Conversions between AE and Python data type
  67. echo.py        Dummy AE server, echoes all data back
  68. tell.py        Primitive AE client
  69. aete.py        Decode 'aete' and 'aeut' resources (incomplete)
  70. gensuitemodule.py
  71.         Read aete/aeut resources and turn them into python
  72.         modules. The *_Suite.py modules have been generated
  73.         with this.
  74. AEservertest.py    A simple AE server, similar to echo but different.
  75.  
  76. In cm:
  77. cmtest.py    List all components in the system plus some info on them
  78.  
  79. In qt:
  80. MovieInWindow.py    Play a movie in a fixed-sized window, stop on mouse-press
  81. VerySimplePlayer.py    Play a movie with the standard quicktime controller.
  82.  
  83. In res:
  84.  
  85. listres.py    List *all* resources in current and in all res files
  86. copyres.py    Copy a resource file
  87. mkerrstrres.py    Read "errors.txt" and create a set of "Estr" resources
  88.  
  89. In snd:
  90.  
  91. playaiff.py    Play an AIFF file
  92. morse.py    Turn text into Morse code
  93. audiodev.py    The standard audiodev.py extended with Mac support
  94. Audio_mac.py    The Mac support for audiodev.py
  95.  
  96.  
  97. Creating new Macintosh interfaces
  98. ---------------------------------
  99.  
  100. These instructions were written up by Jack while he was building the
  101. interface to Lists.h, the macintosh list manager. they may or may not
  102. have a more global scope than exactly that.
  103.  
  104. First, start by copying ...scan.py and ...support.py from another,
  105. preferrably similar type. I started with evt, but that was a mistake
  106. since evt has no "own" object. Ctl or Dlg would probably have been a
  107. better idea.
  108.  
  109. Now, the first thing to do is to comment out the blacklisted types and
  110. functions and the transformation rules for arguments, we'll fill those
  111. in lateron. Also, change the various definitions at the top, so that
  112. the right include file is parsed, and the .py files are generated with
  113. the correct name. If your manager has a type that will be implemented
  114. as a python object you may as well now change the destination() method
  115. to recognize that. (List was funny in this respect, since it has the
  116. list as the last argument in stead of the first).
  117.  
  118. Now run your scanner. This will probably go fine until it tries to
  119. execute the generated code in the ...gen.py module. Look at that file,
  120. it will have formalized "definitions" of all the functions and methods
  121. that will be generated. Look at them all (with the documentation of the
  122. manager you're implementing in hand). Now you'll have to fix the
  123. blacklists and the repair instructions. This is sort of a black art,
  124. but a few guidelines may be handy here: 
  125. - If there are argument types you cannot implement (or want to leave for
  126.   the moment) put them in blacklisttypes. Complex structures come to
  127.   mind, or routine pointers/UPP's. You will probably also want to
  128.   blacklist the routine that disposes of your object (since you'll do
  129.   that in the python destruction routine).
  130. - Various types of buffers are available in bgenBuffer, bgenHeapBuffer
  131.   and macsupport in the bgen directory. These'll let you handle all
  132.   sorts of input and output parameters. You can put instructions in the
  133.   repair list to let the C-arguments be handled by the correct type
  134.   of buffer. Check the other bgen-generated modules for using this for
  135.   passing raw structures and input and output buffers.
  136. - It appears that the parser usually guesses correctly whether a parameter
  137.   is meant for input or output. But, check the routines to be sure.
  138. - Some types are pretty hard to handle but you need the functionality
  139.   the a routine that uses them anyway. Various routines expecting ProcPtrs
  140.   or RegionHandles come to mind. Often, you can use the FakeType class
  141.   to provide a sensible default (i.e. NULL or a pointer to a routine you
  142.   coded in C, or a region specifying "the whole window"). This way, python
  143.   programmers won't get the full functionality but at least they'll get the
  144.   common case. You put the FakeType stuff in ...support.py.
  145.   
  146. Next you'll probably have to write the code to implement your object.
  147. This will probably be a subclass of GlobalObjectDefinition. This goes
  148. into ...support.py. Also, some types used by the manager may look
  149. enough like standard types that you can equate them here (there are a
  150. lot of 2-integer structures that look remarkably like a Point, for
  151. instance).
  152.  
  153. You'll also have to define the Function() and Method() classes. The
  154. OSErrFunctionGenerator and its method-counterpart are particularly
  155. handy for a lot of mac managers.
  156.  
  157. Finally, you'll have to try and compile your resulting C-source, and go
  158. through the steps above until it works. For tlist.py, the test program
  159. for list, I started with the application framework. This is probably a
  160. good idea for any manager that does something to the display, since
  161. ApplicationFramework takes care of all the intricacies of event
  162. handling and decoding (up to a point).
  163.  
  164.